<html>
<!-- $LastChangedDate: 2009-11-07 22:56:33 -0500 (Sat, 07 Nov 2009) $ -->
<!-- Copyright (C) 2004,2009 Jim Brooks http://www.palomino3d.org -->
<head>
<title>Palomino - Lua Scripts</title>
<link rel='stylesheet' type='text/css' href='docs.css'>
<link rel='icon' type='image/png' href='images/favicon.png'/>
</head>
<body>

<!-- ----------------------------------------------------------------------- -->
<h1>Palomino - Lua Scripts</h1>
<p>
&copy;2004,2009&nbsp;&nbsp;Jim E. Brooks
&nbsp;&nbsp;<a href='http://www.palomino3d.org'>http://www.palomino3d.org</a>
</p>
<hr>
<ul>
  <li><a href='index.html'>Index</a></li>
  <li><a href='#Overview'>Overview</a></li>
  <li><a href='#C++ and Lua Partitioning'>C++ and Lua Partitioning</a></li>
  <li><a href='#Execution Flow'>Execution Flow</a></li>
  <li><a href='#List of Lua Scripts'>List of Lua Scripts</a></li>
</ul>
<ul>
  <li><a href='module_lua.html'>lua module</a></li>
  <li><a href='module_game.html'>game module</a></li>
</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Overview'></a>
<h2>Overview</h2>
<p><!--date-->[2008/09]</p>
<p>
<font size='+1'>See also <a href='module_lua.html'>lua module</a>.</font>
</p>
<p>
The simulator is implemented as a mixture of C++ and Lua code.
The core of the simulator is written in C++.
The high-level (missions, game logic, etc) is written in Lua.
In client/server terms, C++ is the server, while Lua is the client.
</p>
<p>
Partitioning of C++ and Lua varies by area.
Lua is fully responsible for mission setup and defining a scene.
By contrast, game logic is a mixture of Lua and C++.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='C++ and Lua Partitioning'></a>
<h2>C++ and Lua Partitioning</h2>
<p><!--date-->[2008/10]</p>
<p>
Summary of functionality partitioned across C++ and Lua:
<br>
<font size='-1'>
Only the C++ core is independent.
All Lua code depends on the C++ core in one way or another.
</font>
</p>

<p>
<font size='+1'><b>C++:</b></font>
</p>
<ul>
  <li>simulator core</li>
</ul>

<p>
<font size='+1'><b>Lua:</b></font>
</p>
<ul>
  <li>scene construction</li>
  <li>keyboard handling</li>
  <li>missions</li>
  <li>updating HUD</li>
</ul>

<p>
<font size='+1'><b>Mixture of C++ and Lua:</b></font>
</p>
<ul>
  <li><a href='module_game.html'>game logic</a></li>
</ul>

<p>
Of the Lua functionality, the most complex is the
<a href='module_game.html'>game logic</a>.
</p>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='Execution Flow'></a>
<a name='Flow of Execution'></a>
<h2>Execution Flow</h2>
<p><!--date-->[2008/09]</p>

<ul>

<li>
C++ transfers execution to startup.lua.
</li>
  <ul>
  <li>scene.lua builds the scene-graph</li>
  <li>mission.lua calls a specific mission_*.lua script</li>
  <li>The player's Craft is created and placed at a location</li>
  <li>If appropriate, aircraft carrier is populated</li>
  <li>Friendly aircraft are animated using Replay mechanism</li>
  </ul>

<li>
Every timer-tick, C++ calls tick.lua.
</li>
  <ul>
  <li>polls keyboard (C++ KeyboardDevice)</li>
  <li>polls joystick button (C++ polls axises)</li>
  <li>updates HUD (C++ does tiny bit of HUD updating)</li>
  <li>updates sound (stall warning etc)</li>
  <li>initiates animation/cut-scenes (rescue helicopter, etc)</li>
  <li>processes commands from queue (enqueued by GUI)</li>
  </ul>

</ul>

<!-- ----------------------------------------------------------------------- -->
<hr>
<a name='List of Lua Scripts'></a>
<h2>List of Lua Scripts</h2>
<p><!--date-->[2008/09]</p>
<ul>

<li>
actors.lua
</li>
<p>
Defines the Player and Friends.
</p>

<li>
cmd.lua
</li>
<p>
Dequeue and execute commands from the simulator's command queue.
</p>

<li>
defs.lua
</li>
<p>
Definitions, constants.
</p>

<li>
events.lua
</li>
<p>
Lua classes can define events to be broadcast to registered listeners.
</p>

<li>
game.lua
</li>
<p>
Game class.  C++ has a Game class too that implements much of the game logic.
</p>

<li>
gfx.lua
</li>
<p>
Graphics-related classes (Vec3, RGBA etc) and functions.
</p>

<li>
hud.lua
</li>
<p>
Lua is responsible for updating the "slow HUD" (low-frequency tick).
For example, Lua is what causes "STALL" and "[PAUSED]" to be displayed.
The C++ classes Hud and Game are involved in rendering the HUD.
</p>

<li>
keyboard.lua
</li>
<p>
Lua responds to keyboard input (C++ responds to joystick input).
</p>

<li>
lib.lua
</li>
<p>
General Lua functions.
</p>

<li>
mission*.lua
</li>
<p>
Scripts for specific missions.
</p>

<li>
replay.lua
</li>
<p>
Wraps underlying C++ Replay class.
</p>

<li>
scene*.lua
</li>
<p>
Defines the scene graph.
scene.lua has a function that populates the scene-graph by
reading a Lua table from a specific scene_*.lua script.
</p>

<li>
sim.lua
</li>
<p>
Bindings to many exported C++ classes.
Some Lua classes extend the functionality of their underlying C++ class.
</p>

<li>
startup.lua
</li>
<p>
The main script.
</p>

<li>
tick.lua
</li>
<p>
Lua scripting is timer-driven.
</p>

<li>
view.lua
</li>
<p>
Classes such as SuperView, ChaseView.  View/window functions.
</p>

</ul>

<!-- ********************************* END ********************************* -->
<hr>
<p align='center'>
<font size='-2'>
<!-- hhmts start -->
Last modified: Sat Nov  7 14:43:30 CST 2009
<!-- hhmts end -->
</font>
</p>

</body>
</html>
